Skip to content

wolfSSL manual: fix PDF build failing on backslashes in API comments - #297

Merged
dgarske merged 2 commits into
wolfSSL:masterfrom
LinuxJedi:fix-pdf-api-backslashes
Nov 12, 2026
Merged

dgarske merged 2 commits into
wolfSSL:masterfrom
LinuxJedi:fix-pdf-api-backslashes

Conversation

@LinuxJedi

Copy link
Copy Markdown
Member

The "wolfssl pdf" step of Docs Build Test is failing on master (for example https://github.com/wolfSSL/documentation/actions/runs/43304393323/job/131483694984):

! Undefined control sequence.
l.30846 ... 0x20-0x7E (OpenSSL writes them as"\xHH

The text comes from new Doxygen comments in wolfssl (doc/dox_comments/header_files/asn_public.h and ssl.h, added with the X509_NAME_oneline escaping change, wolfssl 16ffaad4fe). The build clones wolfssl master, Doxygen writes "\\xHH" out as \xHH, and pandoc passes anything that looks like a TeX command through as raw LaTeX, so xelatex stops. It is not specific to any docs change; every PDF build fails until this is handled.

Fix

pdf-prep now doubles any backslash followed by a letter in the API reference pages (group*, *8h*), outside fenced code blocks and inline code, so pandoc prints it literally. This handles the case generally rather than adding another one-off rule next to the existing \par one. Markdown escapes such as \_ or \* and code are left alone. The HTML build is not affected.

Testing

  • Reproduced the failure locally with the CI toolchain (Dockerfile builder image) against current master of both repositories.
  • With the fix, make pdf and make html both succeed; the PDF build reports no undefined control sequences or references.
  • Across all API pages the rule only changes the three \xHH occurrences, which pandoc now renders as \textbackslash xHH.

New Doxygen comments in wolfssl (asn_public.h and ssl.h, for
X509_NAME_oneline) contain the text "\xHH". pandoc passes anything that
looks like a TeX command through as raw LaTeX, so xelatex stopped with
"Undefined control sequence" and the PDF build failed.

In pdf-prep, double any backslash followed by a letter in the API
reference pages, outside fenced code blocks and inline code, so it is
printed literally. This covers the case generally instead of adding
another one-off rule like the existing \par one. The HTML build is not
affected.
Copilot AI balanced review requested due to automatic review settings November 12, 2026 22:00

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@dgarske dgarske self-assigned this Nov 12, 2026
@LinuxJedi

Copy link
Copy Markdown
Member Author

@claude review

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Comment thread wolfSSL/Makefile Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The escaping logic mishandles existing backslash pairs and Markdown code regions, potentially reintroducing build failures and changing the meaning of published code examples.

2 open issues

Review effort: Balanced

Comment thread wolfSSL/Makefile Resolved
Comment thread wolfSSL/Makefile Resolved
Move the escape step into pdf-escape-backslashes.pl and address review
feedback on the inline perl rule:

- Keep existing Markdown escapes whole, including an already escaped
  "\\". The old rule doubled the second backslash of "\\x", leaving a raw
  "\x" for LaTeX again.
- Recognise ~~~ fences as well as ``` and only close a fence with the
  same character and at least the same length.
- Treat inline code spans by delimiter length, including spans that
  continue onto the next line of a paragraph.

None of these cases occur in the current API output, where the only
escaped text is still the three "\xHH" occurrences.
@dgarske
dgarske merged commit 400cdfa into wolfSSL:master Nov 12, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants